AULTICS TECHNICAL BULLETIN 


MTB #175 
To: MTB Oistribution 
From: Ce. Je Tavares 


Subject: Prooosal for a Graphic Fditor 


JUSTIFICATION 


At presents creation of graphic structures for use with the 
Muitics Graphic System must 52 performed by coding PL/I proce- 
jJures which create, edit, and display these structures on an in- 
dividual basilSe The program must be reeedited and recompiled to 
alter thre structure created. This is especially teuious while 
Oieture descriptions are still in the debugging stage. It is un- 
reasonable to expect users of the granhic system to code special- 
ized routines to create graphic structures every time a nen 
structure is desired, 


PRECEDENTS 


Users of the Version 1 Graphic Sysfem nad available fo them 
an Author-Maintained program, pix_edit, which functiored as an 
interactive nicture editor. With it, users could enter picture 
descriptions, view the results immediately, and perforn limited 
alterations of their pictures. As pix_edit was not cesigned to 
be a generalized editor, it tacked all out the most rudimentary 
means ef altering picture elements (i.e. retyping the entire sub- 
construct.) Users found that it was usually easier fo use a text 
adifor to place the dascription into a file, call pix_edit to 
oarse and disolay the consteuctf, and re-enter the editor to make 
alterations. The author of pix_edit (Ken Pogran) later proposed 
a graphic editor witn extended features in an RFC. The extended 
editor was never implemented, | 


PROPOSAL 


The attached documentation describes a graghic editor very 
much tike that proposed in the RFC mentioned. Because of im- 
oroved structure eéditing capabilities in the Version ? 
graphic _manipulator_s if incoroorates several rew features which 
were not possibte to verform using the Version 1 Q9SmM_ packaye. 
The functionality orovided by this interactiv2 tool would be in- 
valuabte tao both the casual user of graphics and to the imptemen- 
tor of extensive graphics apalications. 


Comments and sugjestions may be mailed to Tavar2se4ulfics on 
System “4 (Phoenix). 
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. Command 
Administrative/User Ping 
12730774 


Nama: graphic_edifor, ge 


Tne graphic_editor is an interactive fool which may be used 
to create and edit graphic structures. It is cadable of storing 
these structures into, and retrieving them from, permanent grapn- 
ic segments (PGS*s)., | | 


Usage 
graohic_editor [segil (seg?2}] e.. (Ssegn) 


1) seqi footionsl) is a pathname specifying a segment to be 
read into the grapnic aditor. Tnis segment mey contain 
a list of editor commands or assignments, in tne same 
format as they might have been typed into the editor 
interactively. The segments will be interpreted by the 
editor in the order svecified. 


If any errors occur while reading any segment specified on 
' the command line, processing of that file will cease. 


When graohic_edifor is ready. to receive input from the 
user*s ferminal, it replies with “Edit.". The user may then 
begin to issue requests, 


Reaquesfs fall into fwo categoriz2s$ commands and assign- 
ments. In generals commands may be terminated witn either a 
semicolon ("3") or a newline. Assignments (due to their ability 
to be quite tengthy) may be terminated only with 3 semicolon. 
Sometimes one of more of the arguments of a command May 62 an 
assignment. In these cases, onty the semicolon is accepted as a 
terminator. | | 


Comments which are enclosed by “/* eas. */" may ba inter- 
spersed with any input tines. 


Symbols 


Symbols ir the granhic_editor are alphanumeric represanta- 
tions of node values. A node number is a “receipt” which tre 
graphic system returns whenever if is asked to create some grapn- 
ic element. (For a more complete description of rode values, 
refer to Section 1 of fhe Graphics Users*® Supplement.) Symbols 
have a value wnich consists of exactly one such nade vatue. 


Symbols may be divided into three classes? the system syme- 
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bol, which is predefined and represents a primitive operation or 
atement; the user symbol, which is defined by the user at some 
time with an assianment$s and tne macroy which is defined by The 
user, but takes “argquments’", and has no permanent value of its 
OWN. 


System symbois have no oermanent value. Fhey take one or 
more arguments, eitner implied or explicit. fre use of a system 
symbol represents a reauast that a new element te created. The 
node vaiue returned from that creation is then used in any subse- 
quant operation of that particular expression. 


Fyamrptes of system symbol expressions ares’ 


vector 12 14 a vector of length (12. 14, 0) 


*"Axaloti*™ uc a text string containing the string 
“Axoloti", aligned by the upper center 
edge. 


array (A,bd,c) an array containing the nodes represent- 
ed oy user symbols a, De ang Ce {See 
Tuples, below.) 


lin dotted A mode element for dotted tines. 


A list of system symbols and descriptions of their use may 
be found at tne erd of tne document. 


User symbols may be uo to 3? characters in tangthe and may 
consist of any combination of upper-case and fower-case alphabet- 
icSs numerals, and tne underscore ("_"), provided that the first 
character is non-numeric. Systen symools and conmands are con- 
Sidered “reserved words", and may not also be used as user syr- 
Dols. Attempts to define commands as Symbols will result in 
ill-formed execution of those commands. 


Fxamoles of user Symbols are? 


foo 
Front _corch 


bolt_23wW3 


User symbols are stored in the graphic symbol table of the worke 
ing graphic segment (WGS). They are transferred to and from 
PGS*s whenever thea “save™, “use™, “put, and “get system com- 
mands are used. (For a more complete explanation of graphic sym- 
bols, see Saction 1 of the Graphics Users* Supptiement.) 
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Macros are user symbols whicn take arguments like system 
Symbo!ts. Whenever a macro exoression is evaluated, the arguments 
supdplied are substifuted for tha dummy arguments with which the 
macro was defined. Macros must be defined by macro assignments. 
For example: 


macro box x y = vec x Gy vac og vy, vec -x Oy vec Q -y} 


defines a macro named “box with dummy arguments “x and “y"™. 


The reference: 
box 10 33 


represents a rectanafe 19 units in x and 39 urits in ys and is 
exactly equivalent to the expression? 


vec 10 G4 vec 8 30, vec -4109 Gy, vec QO =29 


Macro names are stored in the graphic symbo! table of the WGS, 
and may be transferred to ani from PGS‘*s witn the “save™, “use, 
“cut™, and “gat commands. 


Tuples 


A tuple is simply a group of one or more values. Every com- 
olete symbol (i-@. a user symbol, or a macro or system symbol! 
with its arguments) is a tuole in itself (a one-tupie). A tupte 
of more than one element may be expressed as its atlements separa- 
ted by commas, @€.9.2! 


As Dy Db» vec 139 4 3, intensity t+. xxx 
This is 3a tuple of 6 alements. 


fh tuole which has more than one elenent represents more than 
‘one. granhic entity. Therefore, it cannot nave one mode value. 
To convert a tunte to a singie yraphic entitys two system symbols 
are available? arraye and list. Tnese two “functions” gather the 
elements of the tuole into a graphic array, or a graphic {ist 
(respectively). (For a more complet? explanation of graphic ar- 
rays and lists, cee Section 1 of the Graphics Users* Supplement.) 
Tne creation of this array or list produces a node value, which 
may be assigned t9 a user symbol, or may he used without assign- 
ment in some ltarger expression. For example? . 


one_array = array (a9 Ds Cs de bd)? 
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iS an assignment which creates a graphic array with the elements 
(ay bs Ce Jd. and bd, and assigns to “one_array™ the value of this 
list. 


Assignments 


An assignment is an operation which extracts fhe value of 
one tuple and assigns if to another tuple. The assignment opnera- 
tor is the infix “="" sign. 


The simote assignments 
foo = bars 


specifies that the the valua of “foo” is to become the symbol 
“bar. An important point fo «xeep in mind is that this does cot 
mean that “foo" ard “yar"™ poth refer to the identical piece of 
graphic structure. Father, “foo contains “bar", and (of course) 
indirectty also contains the entire Structure contained by “bar”, 
(It is possible to assign the value of a symbol to another sym- 
bol, rather than assigning one symbol to anothers this operation 
will be discussed in the section describing gualified expres- 
Sions.) If “foo™ is undefined at the time of assignment, it wil! 
be created. If it nad a previous value, that value will be re- 
placed. Any other jranhic structures which referanced “foo” will 
still) refer to it, but aAill now contain Cindirectiy) its new 
value. 


In general, only tuotes of tike dimensionality (i.e. having 
the same rumber of elements) may be assigned to each other. For 


example: 


og Ee 2 Sr ae eg OES 
X = arrav (D»y Js 7)$ 


are both valid assignments. However, 

ane, two = three, four. five’ 
is not 3s valid assignment. 

Two exceotiors exist to this rules First, if the object to 
the rignt of the assianment scperator is 3 one-tuple, it may al- 
Ways te “promoted” into the dimensionality of the object to the 


left of the assignment operator. For axample? 


Ae De C = As 
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iS 2quivalent to. 

a= G3 b = dsc: d3 
Tne second excertion is that if the object to the left of the 
assianment operator is a one-tudle, and the cbject to the right 
of tne assigament ooerator is not a ane-tuplie, then the “array” 


operator is assumed. For instance, the assignments? 


4 = Dy Cy, dt 
A = array (b,y.cy d)s 


are equivalent. Nofe that tne promotion facitity and tne impofli- 
citf-array ooerator can never be useJyJ simultaneousty. This feae 
ture adaisaltows stafements such as? 

one, fwo = three, four, fives 
which more probably represents a user error than a useful Statfe- 


ment. 


Assignments also nave values. Tne value of an assignment is 
the value of the tupte into which tne assignment is done. For 
examote, the value of 

foo = bar3 


is the new value of “foo™". This feature allows nested assign- 
mentS,s as in the following example? 


Oic = Some_setpos, (line = vector 100)% 
Tnis is ?auivalernt to: 


fine = vector 1093 
nic = Some_sefpos, fines 


No te the us2 of the parentheses for precedence definition. The 
parentheses in the expression area necessary Since tuple formation 
is a “stronger” ovteration than assignment. If the exoression had 
been written ass 

pic = Ssome_setpos, tine = vector 1603 


it would have been oerformed as the overations? 


some_setoos, line = vector 1003 /* a. promotion */ 
pic = some_setoo3,. lines 7/* an implicit array */ 
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Quaiified Exoressions 
It is possitte to refer to any element (or tuole of ele- 
ments) of a symbol which represents an array or list by the use 
of qualified expression. The simolest qualified exoression con- 
sists of a symbol, followed by a oeriod. This represents “the 
vatue of". In our first example, 


fou = bar? 


we assiqned “nar" as the value of “foo™. The retationshin of 
“foo” to “bar” was a sunerior/inferior, or father/son relation- 
ShHide If. instead, we say 


we are assianing the yaluyue of “bar” to “foo”. This makes both 
"foo" and “har*S refer to the identical oiece of graphic struc- 
TUre. The symbols now have a “brother™ relationship. 


Successive trailing oeriods denote further tevets of eyvalua- 
tion. Assume The following assignments? 


wee 105 vec Q 10+ vec -1i0»s vec Q °-105 
=c = gd = bOXS 


The following relations hold on these symbols: (Read “=" as “is 
edquivalert to) 


a» = hb 

Bee = De ZC 

Beee = Dee = Co HFT 
Gease = Does = Cos = dad. = box 


The assiaqnment 
Cleese = null = 
actually assigns “nult™ to “d™. 
Additional types of qualified exoressions make if possible 
to refer to elements of tists. The element desirad is denoted by 
an inteqer followiny the approoriate fevels of qualification. 


For example, 


bOXx.? 
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is the second elemant of “box™ (vector ¢ 40). Tuntes of contigu- 
ous elements may be specified by using a range expression, which 
consists of two infegers (reoresentiny the first and last element 
desired) separated py a coton ("2"), For example, — 


bottomless_boax = array {(hox.224)3 


will create a symbol which contains an array made up of ail ate- 
ments of “box™ except the first. 


The star ("*") has a spacial meaning in a qualified exores- 
Sion.e If used by itself, e.y. “box.*", it refers to a tupie mage 


up of ali the element of “box. It may also be used as the tast 
oart of a orange expression, 2463-5 “box.?2*", which refers to 3 


tuple made up of all the elemants of “rox” from the secord to the 
last. The assignment 


bottemless_box = array (box.23*) 


is equivatent to the example above. Note that if a star occurrs 
in a dqualified expression, if must be the Last character. It may 
neither be followed by the second component of a range exoressian 
(eege. “boxe*?3%) nor by further ftevels of qualification fe.g. 
“haxetei “Dd. 


. 2ecause a user may not always Know exactly Now many fevels 
of symbol indirection exist petween the symbol rame ne is working 
with and the arrays or lists with which ne desires to work, any 
reference to an element for range of 2alements) of a fist found in 
a qualified exoression will cause the evaluator to skip any  num- 
ber of levels of symbol indirection. Using one of our previous 
axanpltes to elucidate, this means fhat 


ael Beeseel = NOXel 


This frees fThe user of typing in long, and possibly inaccurate, 
strings of overiodss but alfows the user wro wants to maintain 
fine cortrol of his indirect symbol structuring to do precisely 
that. 


Certain qualified exoressions may nave different meanings on 
the teft side of an assignment than they do on the right side. 
This is oarticulartly inportant to note when using nested assigqn- 
ments. In particular, quatified expressions whicn evaluate fo an 
element of an array or tists or to a fuole of such elements, have 
different meanings in these two contexts. If sucn an expression 
eccurs on the right side of an assignment, its walue consists of 
references fo the values of the elements which make up the list. 
A previous example (“bottomless_box") showed how this usage is 
interpreted. Or the left side of the assignment, nowever, the 
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exoressior denotes element renlacement, For instance, assume the 
followiny assitynments? 


box = vec 10, vec 0 105 vec -10, vec 0 -163 
elem = boxes: 
boxezt = shift -120% 


The first assignment defines “box™. The second assignment causes 
“elem” to refer to the same piece of jyraphic structure which is 
tne third etement of box. The third assignment changes the “top 
of the vox" from a visible vector to an invisible shift ty rede- 
fining the third element of “box™ to be a shift of equal magri- 
tude, This does pat change the value of “eaiem™. Ir simpty 
breaks the association between tne iist “box” and the construct 
which was its fhird element. If the actual changing of that con- 
struct were desired, the third assignment of the above example 
could be replaced with 


box.e3.e = Shift +105 


This assignment would in fact change the value of elem. Q 
side-effect of this poroverty is tnat the expressions “symbol.n" 
and ‘“symbol.ne" are eauivatent on the right side of an assign- 
ment, but are not equivalent on fhe left side. 


Node Constants 


It is possible for node vatues to exist in tne WGS without 
being assigned to any symbol. For instance, a us2r program could 
be cailed from inside the editor to construct a ovarticularty in- 
tricate “canned™ scraphic structur? which may be inefficient or 
difficult to construct by hand. The orogram could orint tne nurm- 
ber of the top-level node in the structure, so that the user 
could “nick it us” by assigning a name to it. The number of this 
node may be typed in, mreceded py the character “#".,. This is 3 
“node constant. 


For eaxamote: if the node constant “#12245" appears as such 
an ovutout, and it is wished to assign to this node the name 
“orphan, the assignment: 


orphan = #422495 


may pe used. 


Octal node values may he exnressed directly ss node con- 
stants without user conversion by immediately following fhe “#" 
with the towercase letter “oo, ecg. “#o144" is equivalent to 


"#100". 
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At thnough node constants and qualified expressions based = an 
node consfants are allowed on the left-hand side of assignment 
Statements, their use is strongly discouraged, 


Commands. 


Following is a tist of editor commands. Arquments) enctosed 
in angle backets ("< «ee. >") denote necessary arguments. Argqu- 
ments encftosed in square brackets (“Ef e+. %4°) =jqdenote optional 
arguments. Fach commana whose argument is signified by <exorn> 
will accept single elements, tuples, assignments, or any combira- 
tion of fhese as its argument. For exampie? : 


display pic = array (house, street, parked_cars); 


serves fhe dual puroose of defining “oic™ and disolaying it. 


> ==> display <exorn> 

di <exern> 
causes fhe screen to be erased and the graphic structure speci- 
fied to be displayed. If fhe argument is a tuole, no erase is 
performed between eacn element of the tuple. 


>a 2-> list Coptions} 
Is Loptions] 
will list selected symbol tables. Any number of options may be 


specified. Tne following options are allowed: 
-commands -com fist the editor commands and their abbreviations. 


“system “sys list the available system symbols and their abo- 
breviations. ; 


~macros -mc fist the defined nacros,. 
-“symbo!s -sym fist tne user synbolts. 

eall -a fist all of the above. 

If no ootions are given, “-symbots”™ is assumed. 
><=-> execute <command_line> 


exec <command tire> 
causes the <command_line> to be passed to the command processor. 
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>=<=> snow <axorn> 
causes an abbreviated descriotion of the tuple <exorn> to be 
nrinted to the user*s terminal. Tf the value represents a termi- 
nal graphic element, ifs contents will be printed. If if repre- 
sents a non-terminal etement, it will be described and the nuther 
of ifs efements sciven. 


>=-=> reotay <exprn> 

like show, excerpt that the entire graphic subtree inferior to the 
chosen node is described in assignment notations, atong with nes- 
ted assignments where appropriate. nis command altows os user to 
“raplay" a graohic structure in a forn acceotabize as innut to the 
graphic_editor. 


>»>-<=> remove <symool1> (symdo0l121] we. Csymboin] 

causes those elements named to pve removed from the table of Known 
user symbols. The symbol in the WGS is aliso deleted, and all 
references to it will be transformed into direct references to 
whatever contents if oossessed. 


yr o-> us@ [frathname] 

causes the permanent yraohic segment (PGS) snecified by [path= 
name} to be loaded into the WSS. This attlows the editor to use a 
orevioustye-constructed set af graphic structures. If ({natnname) 
is not supplied, grapnic_editor will use the vathname which was 
fast suoptiesa te a “use™ or “save™ command. If no such pathname 
exists, an error will occur. If an error occurs during the exe- 
cution of a3 “use command, the “ftast voathname™ will be detliber- 
ately forgotten. 


>-=-=> save [pathname] 

causes the conter.ts of the WGS to be saved in a PGS specified by 
Cpathnamel. If [patnname] is not supptied, graohic_editor ail 
use the pathname which was last supplied to a “use™ or “save"™ 
command. If no such pathname existSs an error will occur. If an 
arror occurs during the execution of a “Save"™ command, the “tast 
pathname” will be deftiberately forgotten. 

> <=> get {model ([foathname)) <synt> [sym2] eee Csymn} 

gefs the structures <symt> wee CSymn) from the PGS specified by 
(Coathname)!. (This notation means that “patnname”, if it is 


given, must be within parentn2seas.) The {mode} argument deter- 
mines what action is taken on attempts to redefine an existing 
name’ 
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“safe leave the old symbol as is and print en error message. 
-force redefine the symbo! and all subsidiary symbolIs. 


“-reptface_only 

-“rpo redefine the symbol. If sunsidiary symools are dunli- 
cated in the WGS, us2 the copies in the WGS. For any 
subsidiary synbdofls not so duplicated, create null 
(empty) symbols. 


-repface_all 

“rpa redefine tne symbol. If sudsidiary symbols are duoli- 
cated in the WGS, use the copies in the WGS. For any 
subsidiary symbols which do nof exist in the KGS, usa 
tne ones in fhe PGS. 


If {(mode] is not specified, “-safe™ will be assumed. The (model 
and ({pathname)] arguments, if oresent, may occur in either 
order, but must crecede any symbol names. 


>--=> put (model [{{pathname)] <symi> (sym2] 2... ([symn] 

stores the structures <sym1{> «2. ([Symni into the PGS specified by 
((pathname)}. The (model argument determines what action is 
taken on attempts to redefine an existing name: 


-Safaea leave the old symbol as is and orint an error message. 
-force redefine tna symbol and all subsidiary symbols. 


“-replace_only 

-rpo redefine the symbol. [f subsidiary symbols are dupli- 
cated in tne PGS», use the copies in the PGS. For any 
subsidiary symbols not so duplicated, create null 
{emoty) symbols. 


-“replace_all 

-rp3 redefine the symbol. If subsidiary symbols are adunli- 
cated in tne PGS, use the copies in tne PGS. For any 
subsidiary symbols whicn do not exist in the PGS- use 
the ones in the WSS. 

If (model is not specified, “-safe™ will be assumed. The permis- 

Sible order of tne arguments is the same as for “get™. 


»>---=> real <pathname> 

causes the file specified by <oathname> to be interprefec as 3 
set of editor commandse Any “read” command encounterea in a file 
will switch the input source to the specified file. When the 
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commands in the specified file nave been exhausted, control will 
return to the user's terminal, or to tne original file issuing 
the “read". Frrors encountered white reading from a Segment wiii 
cause cortro! to be inmediately returned to the user's terminal. 


pm -=> quit 
is used to exit from the editor. 


2==> restart. 
will re-initializa the editor. the working granpnic Segment, and 
all associated symbol fables. Anv remaining command tine, 45 


well as any file “reads*™ pending, will be flushed without execu- 
tion. The state of the aditor after a “restart™’ is the same as 
the state of the editor when it is first invoked. 


><-<--> help 
. 


directs the user to relevant document3atione 


>~=-> macro <name> [Largii ..e. fargn] = <exorn> 

macro show <name1> ee. C[namen] 

macro replay <namet> ees C[namen] 
The first form defines a macro with name <nane>, and arguments 
fargtl] .«.. Cargn). The other forms do for macros what “shorn and 
“reptay™” do for symbols. 


>~==> inout <symnbol> [device_name] 

reyuests that 3s “what™ input be requested fron device 
(device_name). Tha inout will be coliected, interpreted, made 
into a graphic structure, and assigned to symtol <“<symbol>. This 


feature is not yet implementa. 
Jefined System Symbols 


Positional “lements 


All} positional alements take aryuments of the form "x y z". 
If any of these aryuments are not supplied, it will be assumed to 
be zero. It is possible to supply no arguments, only "x", 
oniv “x vy", or all of “x y 7, No ofher combinations (2.7). 
“x z') are parsable. 
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>--> setpositian (sos) 
setooint (sot) 
vector {yoc) 
Shitt (sft) 
point font) 


Modal Fiements 


>---> intensity (int) 
Argument: Integer, 9 through 7, or “of f™ (G), “on" (7), or “fulli™ 
(7). 


>» <-> linetyre (fin) 

Arguments Integers 4 through 5, ors 
“solid” (4) 
“dashed"™ (>?) 
“Jotted" (3) 


*dash_dotted”™ (4) 
“tong_dashegd"™ (5) 


>2-> blink (bik) 
Arguments may be any from the following correspondence list? 
“steady” 0 
“blinking” 1 
»>---> sensitivity (sns) 
Arguments may be ony from the following EOE EES PON aSnee list: 
“insensitive” 0 
“sensitive” 1 


Mapoing flements 

al eas cofaticn (rot) ; 

Arguments: “x_ rotation y_rotation z_rotation”™ in floating or in- 
teger daorees. : 

>» <-> scaling (scl) . 

Argumants: “x scala y_scale z_uscale™ in integer or floating nota- 
tion. 

“Miscellaneous Elements 

>-<-> null 

No arguments. This element represents the “zero node“. It is a 


placeholder, or a graphic no-op. 


Soe} text “string” Lnosiftion3 
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“strina™ (position) 

The second form of the text string is implicitly understooa. The 
opfionai argunrent tposifioni specifies the string alignment. 
(For a more complete explanation of string alianments, refer to 
Section 4 of the Grapnics Users* Supplement.) Any character my 
appear within the string. If it is desired for a quote to appear 
as part of the string, if may »d2@ doubled, as in PL/I. The argu- 
ment may be either an integer or a strings fron the following 
corresponcence list? 


uoper_jeff ul 1 
upper_center uc 2 
uooner_right ur 3 
left | & 
center Cc 5 
right r 6 
lower_lefft V1 7 
lower _center Ic 8 
lower_right (r 9 
>o=—> datablock <elemant> 


data <element> 

creafes a datablock containing the element <efemeant>. Tnis ele- 
ment may be of a form acceptfabite as a Symbot rmam@sy or numeric, or 
a string enclosed in quotes. It may not be a break character 
C5 a s)=60C tc.) )©60Cuntess enclosed in quotes. Oatablocks may be 
used to hold information retevant to tne structure, within the 
structure itself. (For a more complete explanation of data- 
blocks, refer to Section 1 of the Graphics Users’ Supplement.) 


Notes No ayramic ooerations are opresently daAefined for the 
jygraphic_editor. 
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